---
title: Pdf
description: Learn how to handle Pdf inputs in BAML functions
---

Pdf values to BAML functions can be created in client libraries. This document explains how to use these functions both at compile time and runtime to handle Pdf data. For more details, refer to [pdf types](/ref/baml/types#pdf).

<Info>
  `Pdf` instances can be created from URLs, Base64 data, or local files. URL
  processing is controlled by your client's
  [`media_url_handler`](/ref/baml_client/pdf#url-handling) configuration.
  Please note that many websites will block requests to directly fetch PDFs.
</Info>

<Warning>
  Some models like Vertex AI require the media type to be explicitly specified.
  Always provide the `mediaType` parameter when possible for better compatibility.
</Warning>

<Warning>
  The PDF input may need to be put into the `user` message, not the `system` message in your prompt.
</Warning>

## Usage Examples

<CodeBlocks>
```python
from baml_py import Pdf
from baml_client import b

async def test_pdf_input():
    # Create a Pdf object from URL
    pdf_url = Pdf.from_url("https://example.com/document.pdf")
    res1 = await b.TestPdfInput(pdf=pdf_url)
    
    # Create a Pdf object from Base64 data
    pdf_b64 = "JVBERi0K..."
    pdf = Pdf.from_base64(pdf_b64)
    res2 = await b.TestPdfInput(pdf=pdf)
```

```typescript
import { b } from '../baml_client'
import { Pdf } from "@boundaryml/baml"

// Create a Pdf object from URL
const pdfUrl = Pdf.fromUrl('https://example.com/document.pdf')
const res1 = await b.TestPdfInput(pdfUrl)

// Create a Pdf object from Base64 data
const pdf_b64 = "JVBERi0K..."
const res2 = await b.TestPdfInput(
  Pdf.fromBase64(pdf_b64)
)

// Browser-specific helpers
const filePdf = await Pdf.fromFile(file)
const blobPdf = await Pdf.fromBlob(blob)
```

```tsx
import { useTestPdfInput } from '../baml_client/react/hooks'
import { Pdf } from "../baml_client/react/media"

export function TestPdfInput() {
    const { mutate } = useTestPdfInput()

    const handleClick = async () => {
        // Using URL
        const pdfUrl = Pdf.fromUrl('https://example.com/document.pdf')
        mutate(pdfUrl)
        
        // Or using Base64
        const pdf_b64 = "JVBERi0K..."
        const pdf = Pdf.fromBase64(pdf_b64)
        mutate(pdf)
    }

    return (
      <div>
          <button onClick={handleClick}>
              Test Pdf Input
          </button>
      </div>
    )
}
```

```go
package main

import (
    "context"
    
    b "example.com/myproject/baml_client"
)

func testPdfInput() error {
    ctx := context.Background()
    
    // Create a PDF object from URL
    pdfUrl, err := b.NewPDFFromUrl("https://example.com/document.pdf", nil)
    if err != nil {
        return err
    }
    
    result1, err := b.TestPdfInput(ctx, pdfUrl)
    if err != nil {
        return err
    }
    
    // Create a PDF object from Base64 data
    pdfB64 := "JVBERi0K..."
    pdf, err := b.NewPDFFromBase64(pdfB64, nil)
    if err != nil {
        return err
    }
    
    result2, err := b.TestPdfInput(ctx, pdf)
    if err != nil {
        return err
    }
    
    return nil
}
```

```ruby
# Ruby implementation is in development.
```
</CodeBlocks>

## Test Pdf in the Playground

To test a function that accepts a `pdf` in the VSCode playground using a local file, add a `test` block to your `.baml` file:

```baml
function AnalyzePdf(myPdf: pdf) -> string {
  client GPT4o
  prompt #"
    Summarize this Pdf: {{myPdf}}
  "#
}

test PdfFileTest {
  functions [AnalyzePdf]
  args {
    myPdf {
      file "../documents/report.pdf"
    }
  }
}
```

<ParamField path="file" type="string" required="true">
  The path to the PDF file. Supports relative paths (resolved from the current BAML file) or absolute paths. The file does not need to be inside `baml_src/`.
</ParamField>

## API Reference

<Tabs>
<Tab title="Python" language="python">

### Static Methods

<ParamField
  path="from_url"
  type="(url: str) -> Pdf"
>
  Creates a Pdf object from a URL. The media type is automatically set to `application/pdf`.
</ParamField>

<ParamField
  path="from_base64"
  type="(base64: str) -> Pdf"
>
  Creates a Pdf object using Base64 encoded data. The media type is automatically set to `application/pdf`.
</ParamField>

### Instance Methods

<ParamField
  path="is_url"
  type="() -> bool"
>
  Check if the Pdf is stored as a URL.
</ParamField>

<ParamField
  path="as_url"
  type="() -> str"
>
  Get the URL if the Pdf is stored as a URL. Raises an exception if the Pdf is not stored as a URL.
</ParamField>

<ParamField
  path="as_base64"
  type="() -> list[str]"
>
  Get the base64 data and media type if the Pdf is stored as base64. Returns `[base64_data, media_type]`. Raises an exception if the Pdf is not stored as base64.
</ParamField>

<ParamField
  path="baml_serialize"
  type="() -> dict"
>
  Convert the Pdf to a dictionary representation. Returns either `{"url": str}` or `{"base64": str, "media_type": str}`.
</ParamField>

</Tab>
<Tab title="TypeScript" language="typescript">

### Static Methods

<ParamField
  path="fromUrl"
  type="(url: string, mediaType?: string) => Pdf"
>
  Creates a Pdf object from a URL. The `mediaType` parameter is optional but recommended for better model compatibility. If not provided, the media type will be inferred when the content is fetched.
</ParamField>

<ParamField
  path="fromBase64"
  type="(base64: string) => Pdf"
>
  Creates a Pdf object using Base64 encoded data. The media type is automatically set to `application/pdf`.
</ParamField>

<ParamField
  path="fromFile"
  type="(file: File) => Promise<Pdf>"
>
  <Info>Only available in browser environments. @boundaryml/baml/browser</Info>
  Creates a Pdf object from a File object. Available in browser environments only.
</ParamField>

<ParamField
  path="fromBlob"
  type="(blob: Blob, mediaType?: string) => Promise<Pdf>"
>
  <Info>Only available in browser environments. @boundaryml/baml/browser</Info>
  Creates a Pdf object from a Blob object. Available in browser environments only.
</ParamField>

### Instance Methods

<ParamField
  path="isUrl"
  type="() => boolean"
>
  Check if the Pdf is stored as a URL.
</ParamField>

<ParamField
  path="asUrl"
  type="() => string"
>
  Get the URL if the Pdf is stored as a URL. Throws an Error if the Pdf is not stored as a URL.
</ParamField>

<ParamField
  path="asBase64"
  type="() => [string, string]"
>
  Get the base64 data and media type if the Pdf is stored as base64. Returns `[base64Data, mediaType]`. Throws an Error if the Pdf is not stored as base64.
</ParamField>

<ParamField
  path="toJSON"
  type="() => { url: string } | { base64: string; media_type: string }"
>
  Convert the Pdf to a JSON representation. Returns either a URL object or a base64 object with media type, depending on how the Pdf was created.
</ParamField>

</Tab>
<Tab title="Go" language="go">

### Static Methods

<ParamField
  path="NewPDFFromUrl"
  type="(url string, mediaType *string) (*PDF, error)"
>
  Creates a PDF object from a URL. Optionally specify the media type for better model compatibility.
</ParamField>

<ParamField
  path="NewPDFFromBase64"
  type="(base64 string, mediaType *string) (*PDF, error)"
>
  Creates a PDF object using Base64 encoded data. The media type is automatically set to `application/pdf` if not provided.
</ParamField>

### Instance Methods

<ParamField
  path="IsUrl"
  type="() bool"
>
  Check if the PDF is stored as a URL.
</ParamField>

<ParamField
  path="AsUrl"
  type="() (string, error)"
>
  Get the URL if the PDF is stored as a URL. Returns an error if the PDF is not stored as a URL.
</ParamField>

<ParamField
  path="AsBase64"
  type="() (string, string, error)"
>
  Get the base64 data and media type if the PDF is stored as base64. Returns `(base64Data, mediaType, error)`. Returns an error if the PDF is not stored as base64.
</ParamField>

<ParamField
  path="ToJSON"
  type="() (map[string]interface{}, error)"
>
  Convert the PDF to a map representation. Returns either `{"url": string}` or `{"base64": string, "media_type": string}`.
</ParamField>

</Tab>
<Tab title="Ruby" language="ruby">

Ruby implementation is in development.

</Tab>
</Tabs>

## URL Handling

PDF URLs are processed according to your client's `media_url_handler` configuration:

- **[Anthropic](/ref/llm-client-providers/anthropic#media_url_handler)**: By default converts to base64 (`send_base64`) as required by their API.
- **[AWS Bedrock](/ref/llm-client-providers/aws-bedrock#media_url_handler)**: By default converts to base64 (`send_base64`).
- **[OpenAI](/ref/llm-client-providers/open-ai#media_url_handler)**: By default keeps URLs as-is (`send_url`).
- **[Google AI](/ref/llm-client-providers/google-ai-gemini#media_url_handler)**: By default keeps URLs as-is (`send_url`).
- **[Vertex AI](/ref/llm-client-providers/google-vertex#media_url_handler)**: By default keeps URLs as-is (`send_url`).

<Warning>
  Many websites block direct PDF fetching. If you encounter issues with URL-based PDFs, try:
  1. Using `media_url_handler.pdf = "send_base64"` to fetch and embed the content
  2. Downloading the PDF locally and using `from_file`
  3. Using a proxy or authenticated request
</Warning>

## Configuring Media URL Handlers

You can customize how PDF URLs are processed by configuring the `media_url_handler` in your BAML client definition. This is useful when you need to override provider defaults or ensure compatibility with specific model requirements.

```baml
// Basic example: OpenAI client with PDF base64 encoding
client<llm> MyOpenAIClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      pdf "send_base64"  // Convert PDF URLs to base64
    }
  }
}

function AnalyzePdf(pdf: pdf) -> string {
  client MyOpenAIClient
  prompt #"
    Analyze this PDF: {{ pdf }}
  "#
}
```

### Available Modes

The `media_url_handler.pdf` setting accepts the following values:

- **`send_base64`**: Fetch the PDF from the URL and convert it to base64 before sending to the model. Use this when the provider requires base64 encoding or when you want to ensure the content is embedded in the request.

- **`send_url`**: Keep the PDF as a URL and send it directly to the model. The model provider will fetch the content. Note that many providers don't support direct URL fetching for PDFs.

- **`send_url_add_mime_type`**: Keep the PDF as a URL but add MIME type information (`application/pdf`). Useful for providers like Vertex AI that require explicit MIME types.

- **`send_base64_unless_google_url`**: Keep Google Cloud Storage URLs (`gs://`) as-is, but convert all other URLs to base64. Useful when working with Google AI models.

### Provider-Specific Examples

```baml
// OpenAI: Override default (send_url) to use base64
client<llm> OpenAIClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      pdf "send_base64"  // OpenAI requires base64 for PDFs
    }
  }
}

// Anthropic: Override default (send_base64) to use URL
client<llm> AnthropicClient {
  provider anthropic
  options {
    model "claude-3-5-sonnet-20241022"
    api_key env.ANTHROPIC_API_KEY
    media_url_handler {
      pdf "send_url"  // Anthropic supports both URL and base64
    }
  }
}

// Vertex AI: Use URL with MIME type
client<llm> VertexClient {
  provider vertex-ai
  options {
    model "gemini-1.5-pro"
    project "your-project"
    location "us-central1"
    media_url_handler {
      pdf "send_url_add_mime_type"  // Vertex requires MIME type
    }
  }
}

// Google AI: Use conditional handling for GCS URLs
client<llm> GoogleAIClient {
  provider google-ai
  options {
    model "gemini-1.5-pro"
    api_key env.GOOGLE_API_KEY
    media_url_handler {
      pdf "send_base64_unless_google_url"  // Keep gs:// URLs, convert others
    }
  }
}

// You can configure multiple media types independently
client<llm> MultiMediaClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      image "send_base64"
      audio "send_url"
      pdf "send_base64"
      video "send_url"
    }
  }
}
```

<Info>
  You can configure different handling modes for each media type (`image`, `audio`, `pdf`, `video`) independently in the same client.
</Info>

## Model Compatibility

Different AI models have varying levels of support for PDF input methods **(As of July 2025)**:

| Provider / API         |   | PDF Input Support                                                                                                   |
|-----------------------|---|----------------------------------------------------------------------------------------------------------------------|
| **Anthropic**         | ✓ | Accepts PDFs as a direct https URL or a base‑64 string in a document block. |
| **AWS Bedrock**       | ✓ | PDF must be supplied as raw bytes (base‑64 in the request) or as an Amazon S3 URI (s3:// style). Ordinary https links are not supported. |
| **Google Gemini**     | ✓ | Provide as inline base‑64 or upload first with media.upload and use the returned file_uri. The model does not fetch http/https URLs for you. |
| **OpenAI**            | ✓ | PDF support (added March 2025) via base‑64 in the request. Supplying a plain URL is not accepted. |
| **Google Vertex AI**  | ✓ | Accepts either base‑64 data or a Cloud Storage gs:// URI in a file_data part; you must set mime_type (for PDFs use application/pdf). Generic https URLs are not allowed. |

<Info>
  For most models, direct https URLs are not accepted (except Anthropic). Prefer using base64, file uploads, or the appropriate cloud storage/file upload mechanism for your provider. Always specify the correct MIME type (e.g., application/pdf) when required.
</Info> 